Summary

Two related pieces of work on the Codespace XML-pipeline scaffold:

1. Documentation consistency fixes — corrected inconsistencies that would mislead a new contributor.
2. User Story 3 — migration-safety compare (tasks T021–T023) — diff freshly generated XML against a known-good reference and catch the schema-valid-but-different case (FR-015, SC-005).

This advances the task list from 20/34 → 23/34 complete. Remaining: US5 (generated schema docs/ERD) and US4 (bundle + CI drift gate).

1. Doc fixes

• tasks.md: the summary count was stale (8 done / 26 remaining) — corrected to match the body.
• quickstart.md: pointed contributors at docs/onboarding.md and docs/delivery-plan.md, neither of which existed. Repointed the plan reference to specs/, and added a real docs/onboarding.md (satisfies SC-007) wired into the MkDocs nav.
• Python version drift: a few 3.11 references where the project pins 3.9.4 (the devcontainer feature, quickstart prerequisites, plan/research). Rejected-alternative mentions of 3.11/3.12 left intact.

2. US3 — compare

• src/acoustic_dataset/compare.py — canonicalising comparison. The equality key uses C14N with rewrite_prefixes so attribute order, whitespace, namespace prefix, and comments are cosmetic; the diff renderer strips namespaces for a readable, prefix-independent unified diff. Pure functions shared by the CLI and tests.
• cli.py — compare <generated> <reference>: exit 0 = clean match, 1 = meaningful difference (prints the diff) or IO/parse error.
• Makefile — make compare with overridable COMPARE_GENERATED / COMPARE_REFERENCE, defaulting to the pipeline output vs the shipped reference.
• examples/reference/trial_known_good.xml — a labelled placeholder known-good reference, serialised with a ds: prefix to prove cosmetic-difference tolerance.
• tests/integration/test_compare.py — cosmetic-ignored (attribute order, whitespace, prefix, comments), schema-valid-but-different surfaced (an in-band Level change), and the CLI exit-code contract.
• Docs — marked compare done in tasks.md / commands.md / onboarding.md; added a how-to guide and nav entry.

Demonstration

$ make pipeline && make compare
pipeline ok: 10 band(s) -> build/acoustic_dataset.xml (schema-valid, round-trip-equal)
match: build/acoustic_dataset.xml is canonically identical to examples/reference/trial_known_good.xml   # exit 0

$ python -m acoustic_dataset.cli compare /tmp/changed.xml examples/reference/trial_known_good.xml
different: /tmp/changed.xml is schema-shaped but differs from examples/reference/trial_known_good.xml
@@ -14,7 +14,7 @@
           <Bearing>0.000</Bearing>
-          <Level>134.000</Level>
+          <Level>144.000</Level>                                                                        # exit 1

Verification

• pytest — 27 passed (was 16; +11 for compare)
• ruff check src tests — clean
• mypy on the new modules — clean
• mkdocs build --strict — clean (no broken links)

https://claude.ai/code/session_01CFHWZFcZ3ecni6bzZ2AXdq

Generated by Claude Code